<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>cat API | Elasticsearch: 权威指南 | Elastic</title>
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
</head>
<body>
<div class="main-container">
    <section id="content">
        
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原文地址: <a href="https://www.elastic.co/guide/cn/elasticsearch/guide/current/_cat_api.html" rel="nofollow">https://www.elastic.co/guide/cn/elasticsearch/guide/current/_cat_api.html</a>, 版权归 www.elastic.co 所有<br/>
                            英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/guide/current/_cat_api.html" rel="nofollow">https://www.elastic.co/guide/en/elasticsearch/guide/current/_cat_api.html</a>
                            </div>
                        <!-- start body -->
                  <div class="page_header">
<b>请注意:</b><br>本书基于 Elasticsearch 2.x 版本，有些内容可能已经过时。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch: 权威指南</a></span>
»
<span class="breadcrumb-link"><a href="administration.html">管理、监控和部署</a></span>
»
<span class="breadcrumb-link"><a href="cluster-admin.html">监控</a></span>
»
<span class="breadcrumb-node">cat API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="_pending_tasks.html">« 等待中的任务</a>
</span>
<span class="next">
<a href="deploy.html">部署 »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="_cat_api"></a>cat API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elasticsearch-cn/elasticsearch-definitive-guide/edit/cn/500_Cluster_Admin/40_other_stats.asciidoc">edit</a>
</h2>
</div></div></div>
<p>如果你经常在命令行下工作，<code class="literal">cat</code> API 对你会非常有用。

用 Linux 的 <code class="literal">cat</code> 命令命名，这些 API 被设计成像 *nix 命令行工具一样工作了。</p>

<p>他们提供的统计和前面已经讨论过的 API ( 健康、<code class="literal">节点统计</code> 等等 ) 是一样的，但是是以表格的形式输出，而不是 JSON。

对于系统管理员来说这是 <em>非常</em> 方便的，你仅仅想浏览一遍集群或者找出内存使用高的节点而已。</p>

<p>通过 <code class="literal">GET</code> 请求发送 <code class="literal">cat</code> 命名可以列出所有可用的 API：</p>

<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat

=^.^=
/_cat/allocation
/_cat/shards
/_cat/shards/{index}
/_cat/master
/_cat/nodes
/_cat/indices
/_cat/indices/{index}
/_cat/segments
/_cat/segments/{index}
/_cat/count
/_cat/count/{index}
/_cat/recovery
/_cat/recovery/{index}
/_cat/health
/_cat/pending_tasks
/_cat/aliases
/_cat/aliases/{alias}
/_cat/thread_pool
/_cat/plugins
/_cat/fielddata
/_cat/fielddata/{fields}</pre>
</div>
<p>许多 API 看起来很熟悉了（是的，上面还有一只猫呢 :)）。让我们看看<code class="literal">Cat Health</code> API：</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat/health

1408723713 12:08:33 elasticsearch_zach yellow 1 1 114 114 0 0 114</pre>
</div>
<p>首先你会注意到的是，响应是表格形式的纯文本，而不是 JSON。其次你会注意到，默认情况下各列是没有表头的。这都是模仿 *nix 工具设计的，因为它假设一旦你对输出熟悉了，你就再也不想看见表头了。</p>

<p>要启用表头，添加参数<code class="literal">?v</code>即可：</p>

<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat/health?v

epoch   time    cluster status node.total node.data shards pri relo init
1408[..] 12[..] el[..]  1         1         114 114    0    0     114
unassign</pre>
</div>

<p>
嗯，好看多了。

我们现在看到 时间戳、集群名称、状态、集群中节点的数量等等 — 所有信息和 <code class="literal">cluster-health</code> API 返回的都一样。</p>

<p>再看下<code class="literal">cat</code> API 里面的<code class="literal">node-stats</code>：</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat/nodes?v

host         ip            heap.percent ram.percent load node.role master name
zacharys-air 192.168.1.131           45          72 1.85 d         *      Zach</pre>
</div>
<p>我们看到集群里节点的一些统计，不过和完整的 <code class="literal">node-stats</code> 输出相比而言是非常基础的。

你可以包含更多的指标，但是比起查阅文档，让我们直接问 <code class="literal">cat</code> API 有哪些可用的吧。</p>

<p>你可以通过对任意 API 添加参数 <code class="literal">?help</code> 来做到这点：</p>

<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat/nodes?help

id               | id,nodeId               | unique node id
pid              | p                       | process id
host             | h                       | host name
ip               | i                       | ip address
port             | po                      | bound transport port
version          | v                       | es version
build            | b                       | es build hash
jdk              | j                       | jdk version
disk.avail       | d,disk,diskAvail        | available disk space
heap.percent     | hp,heapPercent          | used heap ratio
heap.max         | hm,heapMax              | max configured heap
ram.percent      | rp,ramPercent           | used machine memory ratio
ram.max          | rm,ramMax               | total machine memory
load             | l                       | most recent load avg
uptime           | u                       | node uptime
node.role        | r,role,dc,nodeRole      | d:data node, c:client node
master           | m                       | m:master-eligible, *:current master
...
...</pre>
</div>
<p>(注意：这个输出为了页面简洁而被截断了)。</p>
<p>第一列显示完整的名称，第二列显示缩写，第三列提供了关于这个参数的简介。

现在我们知道了一些列名了，我们可以用参数 <code class="literal">?h</code> 来明确指定显示这些指标：</p>

<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET /_cat/nodes?v&amp;h=ip,port,heapPercent,heapMax

ip            port heapPercent heapMax
192.168.1.131 9300          53 990.7mb</pre>
</div>
<p>因为 <code class="literal">cat</code> API 试图像 *nix 工具一样工作，你可以使用管道命令将结果传递给其他工具，比如 <code class="literal">sort</code> 、 <code class="literal">grep</code> 或者 <code class="literal">awk</code> 。例如，通过以下方式可以找到集群中最大的索引：</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">% curl 'localhost:9200/_cat/indices?bytes=b' | sort -rnk8

yellow test_names         5 1 3476004 0 376324705 376324705
yellow .marvel-2014.08.19 1 1  263878 0 160777194 160777194
yellow .marvel-2014.08.15 1 1  234482 0 143020770 143020770
yellow .marvel-2014.08.09 1 1  222532 0 138177271 138177271
yellow .marvel-2014.08.18 1 1  225921 0 138116185 138116185
yellow .marvel-2014.07.26 1 1  173423 0 132031505 132031505
yellow .marvel-2014.08.21 1 1  219857 0 128414798 128414798
yellow .marvel-2014.07.27 1 1   75202 0  56320862  56320862
yellow wavelet            5 1    5979 0  54815185  54815185
yellow .marvel-2014.07.28 1 1   57483 0  43006141  43006141
yellow .marvel-2014.07.21 1 1   31134 0  27558507  27558507
yellow .marvel-2014.08.01 1 1   41100 0  27000476  27000476
yellow kibana-int         5 1       2 0     17791     17791
yellow t                  5 1       7 0     15280     15280
yellow website            5 1      12 0     12631     12631
yellow agg_analysis       5 1       5 0      5804      5804
yellow v2                 5 1       2 0      5410      5410
yellow v1                 5 1       2 0      5367      5367
yellow bank               1 1      16 0      4303      4303
yellow v                  5 1       1 0      2954      2954
yellow p                  5 1       2 0      2939      2939
yellow b0001_072320141238 5 1       1 0      2923      2923
yellow ipaddr             5 1       1 0      2917      2917
yellow v2a                5 1       1 0      2895      2895
yellow movies             5 1       1 0      2738      2738
yellow cars               5 1       0 0      1249      1249
yellow wavelet2           5 1       0 0       615       615</pre>
</div>
<p>通过添加 <code class="literal">?bytes=b</code> ，我们关闭了人类可读的数字格式化，强制它们以字节数输出。随后通过管道命令将输出传递给 <code class="literal">sort</code> 让索引按大小（第八列）排序</p>

<p>不幸的是，你会注意到 Marval 索引也出现在结果中，但是我们目前并不真正在意这些索引。让我们把结果传递给 <code class="literal">grep</code> 命令来移除提到 Marval 的数据：</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">% curl 'localhost:9200/_cat/indices?bytes=b' | sort -rnk8 | grep -v marvel

yellow test_names         5 1 3476004 0 376324705 376324705
yellow wavelet            5 1    5979 0  54815185  54815185
yellow kibana-int         5 1       2 0     17791     17791
yellow t                  5 1       7 0     15280     15280
yellow website            5 1      12 0     12631     12631
yellow agg_analysis       5 1       5 0      5804      5804
yellow v2                 5 1       2 0      5410      5410
yellow v1                 5 1       2 0      5367      5367
yellow bank               1 1      16 0      4303      4303
yellow v                  5 1       1 0      2954      2954
yellow p                  5 1       2 0      2939      2939
yellow b0001_072320141238 5 1       1 0      2923      2923
yellow ipaddr             5 1       1 0      2917      2917
yellow v2a                5 1       1 0      2895      2895
yellow movies             5 1       1 0      2738      2738
yellow cars               5 1       0 0      1249      1249
yellow wavelet2           5 1       0 0       615       615</pre>
</div>
<p>瞧！在通过 <code class="literal">grep</code> (用<code class="literal">-v</code>来过滤掉不需要匹配的数据) 之后，我们得到了一个没有 Marval 混杂的索引排序列表了。</p>

<p>这只是命令行中<code class="literal">cat</code>的灵活性的一个简单示例。

一旦你习惯了使用 <code class="literal">cat</code> ，你会发现它和其他所有 *nix 工具一样并且开始疯狂的使用管道(pipping)、排序(sorting)和过滤(grepping)。

如果你是一个系统管理员并且永远都是 SSH 登录到设备上，那么当然要花些时间来熟悉 <code class="literal">cat</code> API 了。</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="_pending_tasks.html">« 等待中的任务</a>
</span>
<span class="next">
<a href="deploy.html">部署 »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>